<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
	<title>Clustering Plugin Readme</title>
    <style type="text/css">
        BODY {
            font-size : 100%;
        }
        BODY, TD, TH {
            font-family : tahoma, verdana, arial, helvetica, sans-serif;
            font-size : 0.8em;
        }
        H2 {
             font-size : 10pt;
             font-weight : bold;
        }
        A:hover {
            text-decoration : none;
        }
        H1 {
            font-family : tahoma, arial, helvetica, sans-serif;
            font-size : 1.4em;
            font-weight: bold;
            border-bottom : 1px #ccc solid;
            padding-bottom : 2px;
        }

        TT {
            font-family : courier new;
            font-weight : bold;
            color : #060;
        }
        PRE {
            font-family : courier new;
            font-size : 100%;
        }
        #datatable TH {
            color : #fff;
            background-color : #2A448C;
            text-align : left;
        }
        #datatable TD {
            background-color : #FAF6EF;
        }
        #datatable .name {
            background-color : #DCE2F5;
        }
    </style>
</head>
<body>

<h1>
Clustering Plugin Readme
</h1>

<div id="datatable">
<p class="name">&nbsp;<br />
<b>PLEASE NOTE</b> -- Clustering Plugin Users:<br /><br />
Starting with Openfire 3.8.0, this Coherence-based clustering plugin 
has been deprecated in favor of the new Hazelcast-based plugin (/plugins/hazelcast). 
Refer to the Hazelcast plugin documentation or 
<a href="http://community.igniterealtime.org/message/224947#224947">this community post</a>
for additional information.<br /><br />
This plugin has been updated and is expected to be compatible with Openfire 3.8.x. However,
please be advised that <b>no functional testing</b> has been performed on the latest version. 
<i>This plugin is no longer actively maintained.</i><br />&nbsp;
</p>
</div>

<h2>Overview</h2>

<p>
The clustering plugin adds support for running multiple redundant Openfire
servers together in a cluster.  By running Openfire in a cluster, you can
distribute the connection load among several servers, as well as having some
form of failover in the event that one of your servers dies. <font color="red">This
plugin requires a valid <a href="http://www.oracle.com/technology/products/coherence/index.html">Oracle Coherence</a> license.</font> 
</p><p>
In order to run Oracle Coherence in production mode, you will need to secure
licensing for (at least) the Enterprise Edition (EE) of Coherence. Refer to the 
<a href="http://docs.oracle.com/cd/E14571_01/doc.1111/e14860/products.htm#BABIEAJF">
Oracle Fusion licensing docs</a> for more information. Openfire uses the Compute Grid
InvocationService to distribute tasks among the cluster members, but this feature is 
currently available only in EE or Grid Edition (GE).
</p><p>
Note that Coherence is configured to run as GE in development mode by default. 
You can change this setting by overriding the following Java system properties
via /etc/sysconfig/openfire (RPM) or openfired.vmoptions (Windows):
</p><pre>
   -Dtangosol.coherence.edition=EE
   -Dtangosol.coherence.mode=prod
</pre><p>
The current Coherence release is version 3.7.1.</p>

<h2>Installation</h2>

<p>After installing the clustering plugin (by copying clustering.jar into the Openfire plugins directory),
follow steps 1 through 4 for adding Oracle Coherence libraries to Openfire. Step 5
explains how to add this plugin to your Openfire setup.
    <ol>
    <li>Get <a href="http://www.oracle.com/technology/products/coherence/index.html">Oracle Coherence for Java Version</a>.</li>
    <li>Unzip the coherence file and locate <b>coherence.jar</b> and <b>coherence-work.jar</b> in folder coherence/lib.</li>
    <li>Copy <b>coherence.jar</b> and <b>coherence-work.jar</b> to [openfire_home]/plugins/clustering/lib.</li>
    <li>Restart Openfire server.</li>
    </ol>

This version of the plugin has been updated to be compatible with Oracle Coherence Version 3.7.1. Earlier
versions of the clustering plugin are incompatible with Coherence 3.7.1 due to certain changes in the
Coherence API.
</p>

<h2>Upgrading from Openfire Enterprise</h2>

<p>
To upgrade from Enterprise, you will need to shut down your server,
remove the <b>enterprise.jar</b> file and <b>enterprise</b> directory from
the plugins directory in your Openfire install root, and then follow the steps
outlined in the <i>Installation</i> section above.
</p>

<h2>Configuration</h2>

<p>
To enable clustering or monitor the cluster go to: Server --&gt; Server Manager --&gt; Clustering
</p>
<p>
You can change a number of Coherence properties by overriding Java system properties
via /etc/sysconfig/openfire (RPM) or openfired.vmoptions (Windows). For example,
to change the default cluster multicast port number, use the following:
</p><pre>
   -Dtangosol.coherence.clusterport=32380
</pre><p>
Other such settings may be found in the tangosol-coherence.xml file located in the 
coherence.jar file, identified via the "system-property" attribute.</p>

<h2>Compiling from source code</h2>

<p>
If you want to modify or maintain this plugin you will need to get its source code and compile it.
Source code of this plugin is now available in the list of plugins that you get when you download
the <a href="http://www.igniterealtime.org/downloads/source.jsp">Openfire's source code</a>. Follow
these steps to have a working environment:
    <ol>
    <li>Get <a href="http://www.igniterealtime.org/downloads/source.jsp">Openfire's source code</a>.</li>
    <li>Get <a href="http://www.oracle.com/technology/products/coherence/index.html">Oracle Coherence for Java Version</a>.</li>
    <li>Unzip the coherence file and locate <b>coherence.jar</b> and <b>coherence-work.jar</b> in folder coherence/lib.</li>
    <li>Copy <b>coherence.jar</b> and <b>coherence-work.jar</b> to [openfire]/plugins/clustering/lib.</li>
    <li>Add <b>coherence.jar</b> and <b>coherence-work.jar</b> to your IDE build path, or use the Ant build script provided
    with the Openfire source distribution (e.g. "ant -Dplugin=clustering plugin").</li>
    </ol>
</p>

</body>
</html>
